////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package fxplugins.registry
{

import fxplugins.plugin.IPluginMap;

/**
 * // TODO DOCME
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 */
public interface IExtensionRegistry
{
	/**
	 * Initializes a <code>PluginMap</code>'s extension point and extension
	 * instances.
	 */
	function initialize(pluginMap:IPluginMap):void;
	
	/**
	 * Adds a <code>IContributor</code> contributor to the registry.
	 * 
	 * <p>This method usually will take a RegistryContributor instance that
	 * mirrors an <code>IPlugin</code>.</p>
	 * 
	 * @param contributor An <code>IContributor</code> instance.
	 */
	function addContributor(contributor:IContributor):void;
	
	/**
	 * Adds an extension point to the registry.
	 * 
	 * @param contributor The <code>IContributor</code> that owns the extension
	 * point.
	 * @param extensionPointID A unique id usually in reverse domain format.
	 * (<code>org.example.acme.splash</code>)
	 * @return The <code>IExtensionPoint</code> added to the registry.
	 * @param extensionPointName A string indicating the display name of the 
	 * extension point. This name can be <code>null</code>. This parameter refers
	 * to the <code>IPluginExtensionPoint#name</code> property when an extension
	 * point is added by the parser.
	 * @return The <code>IExtensionPoint</code> instance created.
	 */
	function addExtensionPoint(contributor:IContributor,
							   extensionPointID:String,
							   extensionPointName:String):IExtensionPoint;
	
	/**
	 * Adds an extension to the registry.
	 * 
	 * @param contributor The <code>IContributor</code> that owns the extension.
	 * @param extensionID A unique extension id. This id can be 
	 * <code>null</code>.
	 * @param extensionPointID A unique id usually in reverse domain format. 
	 * (<code>org.example.acme.splash</code>)
	 * @param extensionName A string indicating the display name of the 
	 * extension. This name can be <code>null</code>. This parameter refers
	 * to the <code>IPluginExtension#name</code> property when an extension
	 * is added by the parser.
	 */
	function addExtension(contributor:IContributor,
						  extensionID:String,	
						  extensionPointID:String,
						  extensionName:String):IExtension;
	/**
	 * Adds an extension descriptor to the registry.
	 * 
	 * @param contributor The <code>IContributor</code> that owns the extension
	 * descriptor.
	 * @param parentID The registryID of the parent extension or 
	 * extension descriptor.
	 * @param name A String name of the descriptor, this is like a tag name.
	 * This name must be set in either the MXML declaration of the descriptor
	 * or in the <code>PluginOptions</code> subclass.
	 * @param properties The decorated values object of the descriptor. This will
	 * either be an XML node that is transformed into an <code>Object</code> or
	 * a <code>PluginOptions</code> instance declared in MXML.
	 */
	function addExtensionDescriptor(contributor:IContributor,
									parentID:int,
									name:String,
									properties:Object):IExtensionDescriptor
	
	function getContributor(id:int):IContributor;
	
	function getExtensionPoint(nameSpace:String, 
							   pointName:String = null):IExtensionPoint;
	
	function getExtensionPoints():Array;
	
	function getExtension(extensionID:String, 
						  extensionPointID:String = null):IExtension;
	
	function getExtensionFor(pluginID:String,
							 extensionPointName:String,
							 extensionID:String):IExtension;
	
	function getExtensions(extensionPointID:String):Array;
	
	function getExtensionDescriptors(extension:IExtension):Array;
	
	function getExtensionDescriptorsFor(extensionPointID:String):Array;
	
	function getExtensionDescriptorByID(descriptorID:String, 
										extensionPointID:String):IExtensionDescriptor;
}
}